Image.PixelRegion

A PixelRegion represents a collection of pixels in an image. A common use-case is to represent regions or masks in an image and the underlying representation is therefore run-length coded in form of a list of connected row-segments. This makes the representation computationally efficient to work with. The pixels in a PixelRegion need not be connected though, but can consist of isolated pixels or a set of connected regions.

It is assumed that a PixelRegion is used together with an Image object in which it defines the collection of pixels. The PixelRegion therefore knows only about pixel coordinates and is not aware of the Image object’s world coordinate system. For measurements inside the given PixelRegion or for transformations of the PixelRegion requiring the Image world coordinate system, the reference Image object must also be supplied as parameter to the corresponding functions.

The PixelRegion can be obtained as a rasterized Shape object, but there is currently no function for converting a PixelRegion to a Shape object. A PixelRegion can be generated from an Image object, for example through a threshold operation, and it is possible to render a PixelRegion back into an Image object.

Image.PixelRegion.clone(region)
Argument:
Return type:

Image.PixelRegion

Create an independent copy of a pixel region in new allocated memory. Can also be called with a vector of pixel regions.

Image.PixelRegion.contains(region, point)
Arguments:
Return type:

boolean

Return true if the region(s) contains the given point. If more than one region is provided true is returned if the point is inside any of the regions. If more than one point is provided an array is returned with one value for each input point.

Image.PixelRegion.countBorderPixels(region)
Argument:
Return type:

int

Return the number of border pixels of the region. A border pixel is located within the region and with neighboring pixels outside the region. 4-connectivity is used for the neighbor relation.

Image.PixelRegion.countHoles(region)
Argument:
Return type:

int

Return the number of holes in the region. To avoid including very small holes that only represent image noise, consider performing a dilate operation before calling countHoles.

Image.PixelRegion.countPixels(region)
Argument:
Return type:

int

Return the number of pixels within the region.

Image.PixelRegion.createCircle(center, radius)
Arguments:

  • center (Point)

  • radius (float)

Return type:

Image.PixelRegion

Create a pixel region containing all pixels within the given circle. By providing vectors of centers and radii several pixel regions can be created. All vectors must be of equal length.

Image.PixelRegion.createEmpty()
Return type:

Image.PixelRegion

Create an empty region.

Image.PixelRegion.createFromPoints(points, referenceImage, pointDiameter)
Arguments:

  • points (Point)

  • referenceImage (Image)

  • pointDiameter (int)

Return type:

Image.PixelRegion

Create a PixelRegion from a set of 2D points defined in image world coordinates. Any points outside the reference image bounds are ignored. By default, each point sets one pixel in the output region. The region point size can be adjusted by the pointDiameter parameter.

Image.PixelRegion.createRectangle(x0, y0, x1, y1)
Arguments:

  • x0 (int)

  • y0 (int)

  • x1 (int)

  • y1 (int)

Return type:

Image.PixelRegion

Create a pixel region containing all pixels within a rectangle with upper-left corner (x0,y0) and lower-right corner (x1,y1). By providing vectors of corners several pixel regions can be created. All vectors must be of equal length.

Image.PixelRegion.dilate(region, diameter)
Arguments:
Return type:

Image.PixelRegion

Dilate the input region with a disc of the given pixel diameter.

Image.PixelRegion.downsample(inputRegion, factor)
Arguments:
Return type:

Image.PixelRegion

Downsample the pixel region(s) by an integer factor, keeping only rows and columns with coordinates equal to n*factor, where n = 0,1,2,…

Image.PixelRegion.erode(region, diameter)
Arguments:
Return type:

Image.PixelRegion

Erode the input region with a disc of the given pixel diameter.

Image.PixelRegion.fillHoles(region)
Argument:
Return type:

Image.PixelRegion

Fill any holes in a region.

Image.PixelRegion.fillRegion(region, value, inputImage)
Arguments:
Return type:

Image

Set all pixels within the given region(s) in the target image to a specific value in world coordinates. The pixels outside the input region keep their original values. A new image with updated values is returned, and the input image is left unchanged.

Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. If the value parameter is outside the image value range it will be clamped to the closest valid value. The output image inherits the image world coordinate system of the input image.

Missing data handling: The missing data flag is kept in the output image, but the pixels in the fill region will be updated with non missing data.

Image.PixelRegion.fillRegionInplace(region, value, image)
Arguments:
Return type:

Image

Inplace version of the Image.PixelRegion.fillRegion function that modifies the input image. See base function for full documentation.

Image.PixelRegion.findConnected(inputRegions, minSize, maxSize, maxRegionCount, timeoutSeconds)
Arguments:

  • inputRegions (Image.PixelRegion)

  • minSize (int)

  • maxSize (int)

  • maxRegionCount (int)

  • timeoutSeconds (float)

Return type:

Image.PixelRegion

Find the connected components of an input pixel region, i.e., splits a PixelRegion object into a list of separated regions. Only keeps regions with a size (counted in number of pixels) within the range [minSize, maxSize].

Image.PixelRegion.getArea(region, referenceImage)
Arguments:
Return type:

float

Return the area of the specified region. This is equal to the number of pixels in the region times the area of each pixel as specified by the pixel sizes in the x,y-dimensions.

Missing data handling: Any missing data information of the referenceImage is ignored. The area is calculated purely on the pixelRegion and scaled using the pixel scale of the image world coordinate system.

Image.PixelRegion.getBorderRegion(region)
Argument:
Return type:

Image.PixelRegion

Get the border pixels of the input region as a new pixel region. Border pixels are pixels within the input region bordering to pixels outside the region.

Image.PixelRegion.getBoundingBox(region, referenceImage)
Arguments:
Return type:

Shape

Return an axis-aligned box of the region as a rectangle Shape in image world coordinates. To get the bounding box in pixel coordinates instead, just omit the optional referenceImage parameter.

Image.PixelRegion.getBoundingBoxOriented(region, referenceImage, accuracyRad, rotationAngleRad, rotationToleranceRad)
Arguments:

  • region (Image.PixelRegion)

  • referenceImage (Image)

  • accuracyRad (float)

  • rotationAngleRad (float)

  • rotationToleranceRad (float)

Return type:

Shape

Returns the rectangle (not necessarily axis-aligned) of minimum area containing the object. The area is computed in world coordinates. A rectangle is defined by its center, width, height and a rotation around the center point. As the image has a left-handed coordinate system, a positive rotation is in a counter clockwise direction. The angular search range is unlimited by default and for unlimited search, the found box is oriented such that the width is larger or equal to the height and such that the orientation angle in the range (0..PI). A limited search can be specified by providing the center angle (rotationAngleRad) and the tolerance (rotationToleranceRad) of the desired range. By only setting the center angle (rotationAngleRad) and not the tolerance (rotationToleranceRad), a bounding box with a fixed rotation is obtained. This is useful when the orientation of the rectangle is known beforehand. The orientation can be obtained from other functions to find bounding boxes where the orientation is based on a different measure. E.g. Image.PixelRegion.getPrincipalAxes returns the orientation of the major axis of the region.

Image.PixelRegion.getCenterOfGravity(region, referenceImage)
Arguments:
Return type:

Point

Return the center of gravity of the region in image world coordinates.

Missing data handling: Any missing data information of the referenceImage is ignored. The center of gravity is calculated purely on the pixelRegion compensated for image scale and origin.

Image.PixelRegion.getCircularity(region)
Argument:
Return type:

float

Returns a circularity measure that is 1.0 for ideal circles and smaller for other shapes. The measure is robust to high-frequency noise like jagged edges along the circle perimeter, so even noisy circles get a measure close to 1.0. The measure is significantly lower if the overall appearance is rather an ellipse, square or other non-circular shape.

Image.PixelRegion.getCompactness(region, referenceImage)
Arguments:
Return type:

float

Returns the compactness measure of the region (4 * PI * Area / Perimeter^2). This is close to 1.0 for circles and smaller for less compact regions.

Image.PixelRegion.getConvexHull(sourceRegion)
Argument:
Return type:

Image.PixelRegion

Get the convex hull of the input pixel region.

Image.PixelRegion.getConvexity(region)
Argument:
Return type:

float

Returns the convexity measure of the region (region area divided by area of convex hull). This is 1.0 for convex regions and smaller the more non-convex the region is

Image.PixelRegion.getDifference(region1, region2)
Arguments:
Return type:

Image.PixelRegion

Get the set difference of the input regions. Returns a new region containing all pixels present in the first region but not in the second.

If two regions are give, the function returns the difference of the two regions. If one list and one region is given, the function returns a list of regions containing the differences of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise difference of the regions in the lists. The lists must be the same length.

Image.PixelRegion.getElongation(region, referenceImage)
Arguments:
Return type:

float

Get the elongation of the region, defined as the ratio between the principal axes lengths. This measure is also often called eccentricity. The value is 1.0 for circles larger than 1.0 for regions that are elongated in one direction.

Image.PixelRegion.getHistogram(region, image, binCount, minValue, maxValue, referenceSurface)
Arguments:
Return type:

float

Get a histogram of the image values within the specified region. If the image supports missing data, pixels marked as missing are not included in the histogram. If a pixel-world mapping is specified, the histogram is computed using world coordinates. If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. Optionally, a reference surface in world coordinates may be provided, in which case the histogram is based on deviations from the reference surface. The default surface is the plane z=0. See also Image.getHistogram.

Image.PixelRegion.getIntersection(region1, region2)
Arguments:
Return type:

Image.PixelRegion

Get the set intersection of two regions.

If two regions are give, the function returns the set intersection of the two regions. If one list and one region is given, the function returns a list of regions containing the intersections of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise intersection of the regions in the lists. The lists must be the same length.

Image.PixelRegion.getMedian(region, image, referenceSurface)
Arguments:
Return type:

float

Get the median value of the pixels within the region, a special case of Image.PixelRegion.getPercentiles. The median is derived from a histogram and it is approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0.

Image.PixelRegion.getPercentiles(region, image, percentileLevels, referenceSurface)
Arguments:
Return type:

float

Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. All values are derived from a histogram and are approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0.

Image.PixelRegion.getPerimeterLength(region, referenceImage)
Arguments:
Return type:

float

Get the region perimeter length in world units. The length is computed as the sum of distances between individual pixels. Note that this means that the reported perimeters are different than the analytical perimeter for mathematical objects like circles and rectangles.

Image.PixelRegion.getPrincipalAxes(region, referenceImage)
Arguments:
Return type:

float

Get principal axes of the region (orientation and length of major/minor axes, derived from region moments).

Image.PixelRegion.getStatistics(region, image, referenceSurface)
Arguments:
Return type:

float

Get pixel value statistics for pixels belonging to a pixel region. Image world coordinate system values are used and pixels with missing data are excluded. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided, basing the statistics on deviations from that surface. If the statistics can not be calculated, nil is returned. A vector of regions can be provided, in which case four vectors of statistics are returned, one entry for each input region. Any invalid input region in the vector will have the corresponding output entries set to zero.

Image.PixelRegion.getUnion(region1, region2)
Arguments:
Return type:

Image.PixelRegion

Get the set union of two or more regions.

If two regions are give, the function returns the set union of the two regions. If one list of regions is given, the function returns the set union of all regions in the list. If one list and one region is given, the function returns a list of regions containing the unions of each region in the list and the single region. If two lists are given, the function returns a vector of regions containing the pair-wise unions of the regions in the lists. The lists must be the same length.

Image.PixelRegion.getVolume(region, heightMap, referenceSurface)
Arguments:
Return type:

float

Get the volume between a height map and a reference surface within the region or regions. Image world coordinate system values are used. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided. NOTE: Values below the reference surface are disregarded (counted as a zero-volume-contribution). Pixels with missing data are disregarded (counted as a zero-volume-contribution). For other ways of handling missing data, such as filling using nearby data, call the appropriate Image.missingData-function before calling getVolume.

Image.PixelRegion.intersectImage(region, referenceImage)
Arguments:
Return type:

Image.PixelRegion

Get the part of a pixel region within a reference image.

Image.PixelRegion.invert(region, referenceImage)
Arguments:
Return type:

Image.PixelRegion

Get the complement within a reference image, returns a pixel region(s) containing all reference image pixels not in the input region(s).

Image.PixelRegion.isEmpty(region)
Argument:
Return type:

boolean

Check if the region contains zero pixels. If a vector of pixel regions is provided the output is a vector of the same length.

Image.PixelRegion.resize(inputRegion, inputReferenceImage, resizedReferenceImage)
Arguments:
Return type:

Image.PixelRegion

Transform the region using two reference images. Can be used to adapt a region after an image resize.

Image.PixelRegion.resizeScale(inputRegion, scaleX, scaleY)
Arguments:
Return type:

Image.PixelRegion

Transform the region in a way compatible to Image.resizeScale. Can be used to adapt a region after an image resize.

Image.PixelRegion.thin(region)
Argument:
Return type:

Image.PixelRegion

Creates a skeleton region out of the input region.

Image.PixelRegion.toImage(region, referenceImage, valueWorld)
Arguments:
Return type:

Image

Convert the region to an image, using a specified value for pixels within the region. The value is in world coordinates and is clamped to the representable range of the image.

Image.PixelRegion.toPoints2D(region, referenceImage)
Arguments:
Return type:

Point

Get a vector of the pixels contained in the region represented as 2D Point objects. Pixel coordinates are converted to image world coordinates using the reference image. Any parts of the input region that is outside the reference image bounds is ignored.

Image.PixelRegion.toPoints3D(region, referenceImage)
Arguments:
Return type:

Point

Get a vector of the pixels contained in the region represented as 3D Point objects, including a z value from the reference image. Any parts of the input region that is outside the image bounds or contains missing data is ignored.

Image.PixelRegion.toString(pixelRegion)
Argument:
Return type:

string

Get a brief string description of the pixel region. This is equal to the text shown in the debugger to describe the region. Can also be called with a vector of pixel regions.

Image.PixelRegion.toVector(region)
Argument:
Return type:

int

Returns vectors of the Y coordinate and X coordinate start and end, corresponding to the pixel region run length encoded segments.

Image.PixelRegion.touchesImageBorder(region, referenceImage, leftBorder, rightBorder, topBorder, bottomBorder)
Arguments:

  • region (Image.PixelRegion)

  • referenceImage (Image)

  • leftBorder (boolean)

  • rightBorder (boolean)

  • topBorder (boolean)

  • bottomBorder (boolean)

Return type:

boolean

Returns true if a pixel region touches the border of provided image

Image.PixelRegion.touchesRegionBorder(region, referenceRegion)
Arguments:
Return type:

boolean

Returns true if a pixel region touches the border of provided reference region

Image.PixelRegion.transform(inputRegion, transform, referenceImage)
Arguments:
Return type:

Image.PixelRegion

Transform the region using a general 2D Transform object, expressed in image world coordinates.